feat(domains): add Vacuum domain (#35)#67
Merged
Conversation
Adds typed Vacuum entity wrapper exposing intent-specific actions (start, pause, stop, return_to_base, locate, clean_spot, set_fan_speed, send_command) and structured state introspection (is_cleaning/is_docked/is_idle/is_paused/is_returning/is_error, battery_level, fan_speed, fan_speed_list) instead of raw service calls. Optional capabilities degrade safely based on the VacuumEntityFeature bitmask, with supports_* properties for pre-checking. Listener decorators: on_start, on_dock, on_error, on_battery_change, on_fan_speed_change.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #35.
Issue validity
Valid feature request. The issue identifies a real gap: vacuum entities have no typed domain wrapper, forcing users to make raw service calls and parse attributes by hand. This is inconsistent with the typed coverage already provided for Climate, Media Player, Lock, Valve, etc., and violates the project's core mission of providing a Pythonic abstraction over the HA API. The proposed API also aligns with existing domain conventions (intent-specific actions, structured state properties, listener decorators, graceful capability degradation).
Fix
New
src/haclient/domains/vacuum.pydefining aVacuum(Entity)class:is_cleaning,is_docked,is_idle,is_paused,is_returning,is_error,battery_level,fan_speed,fan_speed_list.start(),pause(),stop(),return_to_base(),locate(),clean_spot(),set_fan_speed(speed),send_command(command, params=None).on_start,on_dock,on_error,on_battery_change,on_fan_speed_change.VacuumEntityFeaturebit insupported_featuresand becomes a debug-logged no-op when unsupported, mirroring theLock.open/Valve.stoppattern.supports_*properties expose the same checks for pre-flight inspection.register_domainsoha.vacuum("roborock")works automatically. Exported fromhaclient.domains.NumPy-style docstrings throughout, per AGENTS.md.
Tests / checks
Added
tests/test_domains.pycases:test_vacuum_actions_full_featured— every action dispatches the right service against a fully-featured vacuum.test_vacuum_send_command_without_params—send_commandomitsparamswhen none provided.test_vacuum_unsupported_features_are_noops— actions degrade safely with missing/invalidsupported_features.test_vacuum_state_props— state convenience properties and attribute coercion (including malformed inputs).test_vacuum_listeners—on_start/on_dock/on_error/on_battery_change/on_fan_speed_changefire on the relevant transitions.Validation suite:
pytest tests/ --cov=haclient --cov-report=term-missing --cov-fail-under=95— 270 passed, total coverage 96.84%,vacuum.pyat 100%.ruff check src tests— clean.ruff format --check src tests— clean.mypy src— clean (strict mode, 35 files).